---
title: Webhooks
description: Integrating Terrateam with external systems using webhooks
---

Webhooks allow you to integrate Terrateam with external systems by sending HTTP requests to a specified URL when certain events occur during the Terrateam workflow. While Terrateam does not have a dedicated webhooks feature, you can achieve similar functionality by leveraging [hooks](/reference/configuration/hooks) and [workflows](/reference/configuration/workflows) in combination with Terrateam's built-in environment variables.

## Configuring Webhooks

To configure webhooks in Terrateam, you can use the `hooks` or `workflows` sections in your `.terrateam/config.yml` file. Here's an example configuration that sends a webhook request after an apply operation:

```yaml
hooks:
  apply:
    post:
      - type: run
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply completed for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']
```

In this example, the `hooks.apply.post` section defines a `run` step that uses the `curl` command to send an HTTP POST request to the specified URL with a JSON payload containing a message.

## Webhook Events

You can configure webhooks to be triggered at various points in the Terrateam workflow, such as:

- Before or after a plan operation
- Before or after an apply operation
- On success or failure of a plan or apply step (via `workflows`)

To trigger webhooks at different events, use the appropriate `hooks` or define custom steps in `workflows`.

## Distinguishing Between Success and Failure

Terrateam's `hooks` run after a complete operation but cannot distinguish between success and failure. For conditional behavior, use the `workflows` section with the `run_on` attribute:

```yaml
workflows:
  - tag_query: ""
    apply:
      - type: init
      - type: apply
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply succeeded for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply failed for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']
```

## Using Environment Variables in Webhooks

Terrateam provides built-in environment variables for context-aware payloads:

- `TERRATEAM_DIR`: Directory being processed
- `TERRATEAM_WORKSPACE`: Workspace in use
- `TERRATEAM_PLAN_FILE`: Path to the plan file
- `TERRATEAM_ROOT`: Root path of the repository

## Securing Webhooks

Best practices:

- Use HTTPS for all webhook URLs
- Include a secret token for authentication
- Sanitize inputs on the receiving end
- Use GitHub Secrets to store tokens

```yaml
hooks:
  apply:
    post:
      - type: run
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply complete", "token":"$WEBHOOK_SECRET_TOKEN"}', 'https://example.com/webhook']
```

## Examples

### Slack Notifications via Workflows

```yaml
workflows:
  - tag_query: ""
    apply:
      - type: init
      - type: apply
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-H', 'Content-Type: application/json', '--data', '{"text":"Apply succeeded for $TERRATEAM_DIR"}', '$SLACK_WEBHOOK_URL']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-H', 'Content-Type: application/json', '--data', '{"text":"Apply failed for $TERRATEAM_DIR"}', '$SLACK_WEBHOOK_URL']
```

### Custom Webhook Server

```yaml
hooks:
  plan:
    post:
      - type: run
        cmd: ['curl', '-X', 'POST', '-H', 'Content-type: application/json', '--data', '{"event":"plan_completed", "directory":"$TERRATEAM_DIR", "workspace":"$TERRATEAM_WORKSPACE", "plan_file":"$TERRATEAM_PLAN_FILE"}', 'https://hooks.example.com/terrateam-webhook']
